/**********************************************************************************************/
/* FBL_I_Database.h 	                                                      				  */
/*                                                                       					  */
/* Copyright Paradigma, 1993-2006															  */
/* All Rights Reserved                                                   					  */
/**********************************************************************************************/

#ifndef _FBL_I_Database_h 
	#define _FBL_I_Database_h
#pragma once

// FBL:
#include "VShared/FBL/publ/Util_classes/FBL_DTFormat.h"
#include "VShared/FBL/publ/Interfaces/FBL_I_Connection.h"

// FINAL:
#include "VShared/FBL/publ/Headers/FBL_pre_header.h"


/**********************************************************************************************/
FBL_Begin_Namespace


/**********************************************************************************************/
SMART_INTERFACE(I_Error);
SMART_INTERFACE(I_Database);
SMART_INTERFACE(I_Table);
SMART_INTERFACE(I_Location);
SMART_INTERFACE(I_OStream);
SMART_INTERFACE(I_Link);
SMART_INTERFACE(I_Value);
SMART_INTERFACE(I_PropertyContainer);
SMART_INTERFACE(I_IndexStyle);
SMART_INTERFACE(I_Value);


/**********************************************************************************************/
SMART_ARRAY_OF_CLASS_PTRS( ArrayOfDatabases, I_Database* );


/**********************************************************************************************/
/// interface FBL_SHARED_EXP_CLASS class 
//
//StubInterface
interface FBL_SHARED_EXP_CLASS I_Database : public I_Unknown
{
virtual						~I_Database( void );

	// ---------------------
	// Properties:

		// <Name> [r/o]
							/** Returns the name of database. In fact this is the name of db file.
								This is not the same as Path of db file.
							 	Cannot be changed, because this may require changing of name
								for several disk files. If you need change db name, use OS. */
virtual	const String&		get_Name( void ) const = 0;	//KEEPAS: mName

		// <TableCount> [r/o]
							/// Returns the count of tables in the database.
virtual	ulong				get_TableCount( void ) const = 0;

		// <LinkCount> [r/o]
							/// Returns the count of links in the database.
virtual	ulong				get_LinkCount( void ) const = 0;

		// <Error> [r/o]	
							/** Returns the last error for this db.
								If no error, then returns NULL. */ 
virtual	const I_Error*		get_Error( void ) const = 0;	


		// <SchemaVersion> 	
							/** Schema version of database. */ 
virtual	ushort				get_SchemaVersion( void ) const = 0;	
virtual	void				put_SchemaVersion( ushort inVersion ) = 0;

		//<Size>
							/// Returns size of Database in bytes.
virtual flength				get_Size( void ) const throw() = 0;
		// <IndexCount>
							/// Returns the total count of indexes in this database.
virtual ulong				get_IndexCount( void ) const throw() = 0;	
	
	// ---------------------
	// DateTime properties:

		// <DateFormat> [r/w]
virtual	EDateFormat			get_DateFormat( void ) const = 0;	
virtual	void				put_DateFormat( EDateFormat inValue ) = 0;

		// <DateSep> [r/w]  // On default '/'
virtual	UChar				get_DateSep	 ( void ) const = 0;	
virtual	void				put_DateSep	 ( UChar inValue ) = 0;

		// <TimeSep> [r/w]	// On default ':'
virtual	UChar				get_TimeSep	 ( void ) const = 0;	
virtual	void				put_TimeSep	 ( UChar inValue ) = 0;

		// <CenturyBound> [r/w]	// On default 20
virtual	ushort				get_CenturyBound( void ) const = 0;	
virtual	void				put_CenturyBound( ushort inValue ) = 0;

		// <DTFormat> [r/o]
virtual	const DTFormat*		get_DTFormat( void ) const = 0;


	// ---------------------
	// Storage Properties:

		// <BigEndian> 
							/// Returns endian of database files.
virtual bool				get_BigEndian( void ) const throw() = 0;  

							/// Allow assign before db.Create() the endian for db files.
							/// If it is not called before db.Create() then current OS endian is used.
virtual void				put_BigEndian( bool inValue ) throw() = 0;  

		// <Exists> [r/o]
							/** Return TRUE if this Storage already have files on device.
								After Create() must be TRUE.
								After ThrowOut() must be FALSE. */
virtual bool				get_Exists( void ) const throw() = 0;  

		// <IsOpen> [r/o]
							/** Returns TRUE if storage is opened now. 
								Must be TRUE after Open(), must be FALSE, after Close(). */
virtual	bool				get_IsOpen( void ) const = 0;
		
		// <IsReadOnly> [r/o]
							/** TRUE if Storage is located on locked volume, 
								or its files marked as read-only. */
virtual	bool				get_IsReadOnly( void ) const = 0;

		// <IsRemote> [r/o]
							/** TRUE if DB is located on server. */
virtual bool				get_IsRemote( void ) const = 0;

		// <Location>
							/// Returns the Location of this db storage.
virtual	I_Location_Ptr		get_Location( void ) const throw() = 0;

							/** Assign location for this db storage. */
virtual void				put_Location( I_Location_Ptr inLocation ) = 0;

		// <Mode>						
							/// Returns the Mode for this db.
virtual	DbMode				get_Mode( void ) const throw() = 0;  

							/** Assign the Mode for db volumes. 
								Can be used only before Create().
								Cannot change mode of existed db (at least now). */
virtual void				put_Mode( DbMode inMode ) throw() = 0; 

		// <SegmentSize>
							/// Returns the segment size of Volume(s) for this db in bytes.
virtual	ulong 				get_SegmentSize( void ) const throw() = 0; 	

							/** Assign the segment size for db Volumes. 
								Can be used only before Create().
								Cannot change segment size of existed db (at least now). */
virtual void				put_SegmentSize( ulong inSize ) = 0;						
						


	// ---------------------
	// Storage Methods:

							/// Creates files of this object on Device.
virtual	void				Create( void ) = 0;
		
							/// Opens files of this object on Device.
virtual void 				Open( void ) = 0;

							/// Closes files of this object.
virtual void 				Close( void ) = 0;

							/// Flushes files of object from Cache to Device if needed.
virtual	void				Flush( void ) = 0;

							/// Removes files of this object from Device.
virtual void 				ThrowOut( void ) = 0;

							/// Clone this db to the new one.
virtual void 				CloneDB( 
								I_Database_Ptr 	inTargetDB, 
								bool 			inLoadRecords ) = 0;
								
virtual void 				CloneDB( 
								I_Location_Ptr 	inTargetLocation, 
								bool 			inLoadRecords ) = 0;



	// ---------------------
	// Table Methods:
							/// Returns a table by index (1 - based) or by name.
							/// Returns NULL if table not found. 
virtual I_Table_Ptr			get_Table( ulong inIndex ) const throw() = 0;
virtual I_Table_Ptr			get_Table( const String& inTable ) const throw() = 0;

							/** Returns a table using it unique ID. 
								For tmp table ID is negative. 
								Returns NULL if table not found. */	
virtual I_Table_Ptr			GetTableByID( long inIndex ) const throw() = 0;


	// ---------------------
	// Link Methods:

virtual I_Link_Ptr			get_Link( ulong inIndex ) const throw() = 0;
virtual I_Link_Ptr			get_Link( const String& inTableName ) const throw() = 0;

							/** Returns a link using its unique ID. 
								Returns NULL if link not found. */	
virtual I_Link_Ptr			GetLinkByID( long inIndex ) const throw() = 0;


	// ---------------------
	// Value Methods:

							/**	This is a virtual factory of Values.
								This allow create values which know if they are from 
								VKenrel or from VClient DLL. */
virtual I_Value_Ptr 		CreateValue(
								VALUE_TYPE 	inType, 
								ushort		inFlags,
								void*		inData = NULL) = 0;

	// ---------------------
	// DB Schema Methods:
	
							/** Creates a new Table in the Database.
								You can ask for tmp table. Such Table will be automatically
								destroyed on the next open, in case of app failure. 
								Also you can specify the storage for this Table.
								Note, for RAM-based db, we cannot create Disk-based table. 
								
								Errors:
									xTableError{ ERR_TABLE_BAD_NAME, ERR_TABLE_ALREADY_EXISTS }	*/
virtual	I_Table_Ptr			CreateTable( 
								const String& 		inName,
								ETableKind			inTableKind = kTblPermanent,
								EStorageType		inStorage = kStorage_Default,
								TableStructure		inTableStructure = kTable_Separate ) = 0;

							/* Removes table from database.							
								Errors:
									xConstraintError{ ERR_CONSTRAINT_PRIMARY_KEY_HAVE_FOREIGN_KEY } */
virtual	void				DropTable( I_Table_Ptr inTable ) = 0;

							/** Creates a new Link in the Database.
								Errors:
									xLinkError{ ERR_LINK_BAD_NAME, ERR_LINK_NAME_NOT_UNIQUE } */
virtual	I_Link_Ptr			CreateLink( 
								const String&					inName,
								ELinkKind						inKind,
								Const_I_PropertyContainer_Ptr	inProperties,
								bool							inTemporary = false, 
								bool							inRegisterInTable = true) = 0;

							/// Remove link from database.
virtual	void				DropLink( I_Link_Ptr inLink ) = 0;


	// ---------------------
	// IndexStyle API methods:

virtual IndStyle_ID 		GetNextIndStyleID( bool inTemporary ) throw() = 0;

virtual I_IndexStyle_Ptr	get_IndexStyle_ByIndex( ulong inIndex ) const throw() = 0;

							/** Returns an object of IndexStyle with the specified name.
								If not found then returns NULL.	
							*/
virtual I_IndexStyle_Ptr	get_IndexStyle( IndStyle_ID inIndStyleID ) const throw() = 0;
virtual I_IndexStyle_Ptr	get_IndexStyle( const String& inName ) const throw() = 0;

virtual ulong				get_IndexStyleCount( void ) const throw() = 0;

							/** Returns a new object of IndexStrPeefs.
								@error: ErrNameNotUnique. */
virtual	I_IndexStyle_Ptr	CreateIndexStyle( 
								const String& 	inName,
								bool			inTmp = false ) = 0;

							/** Remove from database the specified Prefs */
virtual void				DropIndexStyle( I_IndexStyle_Ptr inPrefs ) = 0;
	
	// ---------------------
	// Utility methods:

							/// Compact the database.
virtual void 				Compact( void ) = 0;

							//! Swap segments of db volumes to remove fragmentation.
							//! Do not affect size of database.
							//! Should be used after Compact().
virtual void 				Defragment( void ) = 0;

							/**	Performs diagnose of the database. Writes 
								diagnostic information to the stream accordingly 
								specified verbose level. 
								@param inOut - stream for output messages.
								@param inLevel - specifies the amount of diagnostic messages
									to be produced during operation. */
virtual bool 				Diagnose( 
								I_OStream_Ptr inOut,
								EVerboseLevel inLevel = kVerbose_Normal ) = 0;

virtual void				Reindex( void ) throw() = 0;

							/// Repaire the database.
virtual void 				Repair( void ) = 0;

							// Assign 4-letters MAC types for db files.
virtual void				SetMacTypes(
								OSType inDescType, 
								OSType inDatType, 
								OSType inBlbType, 
								OSType inIndType ) = 0; 

	// ---------------------
	// Dump/LoadDump:


							/**
								Dumps the database to the specified disk location.
								Produce XML or SQL dump as specified.

								@param inDatabase - database to be dumped.
								@param inDumpLocation - location of dump file that must be loaded.
								@param inDumpType - kXML or kSQL dump.
								@param inDumpData - specify if should be dumped only structure, records or both.
								@param inFormatDump - if TRUE then produce formatted dump file, which can be easy read 
											by human, but such file has bigger size, because contains more spaces and TABs.
								@param inEncoding - target text encoding. */
virtual void				Dump( 
								I_Location_Ptr	inDumpLocation,
								DUMP_TYPE		inDumpType,
								EDumpData		inDumpData = kStructureAndRecords,	
								bool			inFormatDump = true,
								OS_Type			inOSType = kOsDefault,
								const char*		inEncoding = "UTF-16" ) = 0;


							/** 
								Loads the specified dump file into a new fresh database.
								LoadDump() create disk files of this db, create its structure according to dump
								and import records from dump into created tables.

								@param inNewEmptyDatabase - object of FBL::I_Database. Must be created by user because 
											user may want I_SqlDatabase or other database object. 	
								@param inDumpLocation - location of dump file that must be loaded.
								@param inNewDbLocation - location for new database.
								@param inDumpType - kXML or kSQL dump. */
virtual void				LoadDump( 
								I_Location_Ptr	inDumpLocation,
								I_Location_Ptr	inNewDbLocation,
								DUMP_TYPE		inDumpType,
								const char*		inEncoding = "UTF-16" ) = 0;

	public://///////////////////////////////////////////////////////////////////////////////////	 

// Last inserted RecID:

virtual	REC_ID				get_LastInserted_RecID( void ) const throw() = 0;

}; 


/**********************************************************************************************/
FBL_End_Namespace

#include <VShared/FBL/publ/Headers/FBL_post_header.h>

#endif // _FBL_I_Database_h
